In this chapter we'll develop a robust user-generated-content (UGC) application leveraging the flexible contest Feature Block. This feature enables rapid development of brand-able UGC experiences by abstracting away common developer concerns such as file uploads & moderation.

Note: Contests are relatively more complex than other features, we'll be introducing several new concepts, be patient and give yourself more time on this chapter than previous chapters.

The walkthrough builds on Chapter 4 - Golden Ticket Sweepstakes - it assumes you are familiar with the signup_form Feature Block.

After completing this chapter you'll be able to create complete contest experiences in your applications.

Blush Magazine Celeb Photo Contest

Blush Magazine wants their community of celebrity obsessed fans to submit their favorite before-and-after photos. Users should be able to upload photos from their computer as well as browse a gallery of approved photos.

Contest Workflow

Before continuing its important to familiarize ourselves with the workflow of a contest:

1. User selects a call-to-action to enter the contest & is presented with an entry_form
2. The entry form asks for registration information – information about themselves they need to provide one-time
3. The entry form also accepts submission information – the actual content of their entry (any combination of text, photo, video)
4. After submitting the entry form, they see a success message
5. By default, the user's contest entry is pending and can be moderated via the Involver Audience Management Platform (AMP)
6. Approved entries are shown in the gallery

Lets get started!

1. In your SML application, paste in the following code:

   <h3>Blush Magazine Celeb Photo Contest</h3>
   <p>Show us your favorite before and after photos of celebs!</p>
   
   <hr>
   
   {% contest %}
   {% endcontest %}
   

1. Click "Save Changes". You should now see a new row in the Features table for a "default" contest.
2. Click "Configure" under Actions for the contest Feature Block settings.
3. Check the box that says "Automatically Approve Contest Entries" & set "Max Contest Entries Per User" to 999 – for development these settings make testing easier
4. Click "Save Settings"
5. Click "Return to Facebook Page".
6. You should see a message says that the Contest has not been built / is incomplete.

The Contest is incomplete because we have not specified the entry form and corresponding success experience.

Adding an Entry Form

In order to build our entry form we'll need to introduce ourselves to a new concept in the language: Partials

Partials 101

At a very high level, partials allow you to define & render small units of code

With partials you can:

• Modularize your code by breaking a template into smaller pieces
• Have SML run when a user takes a particular action, not just at page load
• Late-bind context variables – enabling you to re-render a partial with different values

If this sounds fuzzy don't worry. The best way to learn partials is by using them. We'll use partials to build out the contest submission flow.

1. Update your SML to now read:

   {% partial name: "form" %}
     {% contest_form %}
       <h4>Celeb Photo Contest Entry Form</h4>
   
       {% unless contest_user_is_registered %}
         <div>
   	Name: <input type="text" name="registration[name]"><br>
           Email: <input type="text" name="registration[email]"><br>
         </div>
       {% endunless %}
   
       <hr>
   
       Celeb: <input type="text" name="submission[celeb]"><br>
       Before Photo: {% image_upload_field name:'submission[before_photo]' %}<br>
       After Photo: {% image_upload_field name:'submission[after_photo]' %}<br>
   
       <div>
         <input type="submit" value="Submit">
       </div>
   
     {% endcontest_form %}
   {% endpartial %}
   
   
   {% partial name: "confirmation" %}
     <h4>Success!</h4>
   
     <p>Thank you, <strong>{{ contest_entry.registration.name }}</strong> for submitting your entry.</p>
   
     <div>
       Email: {{ contest_entry.registration.email }}<br>
       Before Photo: <img src="{{ contest_entry.submission.before_photo }}"><br>
       After Photo: <img src="{{ contest_entry.submission.after_photo }}">
     </div>
   {% endpartial %}
   
   <h3>Blush Magazine Celeb Photo Contest</h3>
   <p>Show us your favorite before and after photos of celebs!</p>
   
   <hr>
   
   {% contest %}
     {% contest_form_link entry_form_partial: "form" success_partial: "confirmation" %}
        Click here to enter
     {% endcontest_form_link %}
   {% endcontest %}
   

1. Click "Save Settings" then "Return to Facebook Page"
2. Click the link and submit your entry. If all goes well, you should see your success message confirming your entry.

Entry Form Code Review

Lets take a look at the Entry Form partial in detail:

Contest Form

• Every contest entry form must be wrapped in a contest_form tag
• Like signup_form, you use HTML form fields to collect information
• You many also use special upload field SML tags which enable rich media uploads of photos and video

Contest Form Field Naming Rules

1. Any fields that you wish to collect specific to the user’s registration are defined using an input name in the format registration[field_name]
2. Similarly, any fields that belong to the actual entry submission have input names in the format of submission[field_name]

Contest Form Context Variables

You have access to several context variables in the entry form:

• contest_user_is_registered (boolean) - true if the user entering has a one or more contest registrations in the system
• contest_user (contest_user) - Access to the user's personal information. These attributes are imported from the social network the application lives in
• contest.rules_text (string) - Rules text configured in the contest feature's settings
• contest.rules_url (string) - Rules URL configured in the contest feature's settings

Success Message Context Variables

You have access to the same context variables above with addition to:

• contest_entry - Access to the entry the user just submitted. Use dot notation to reference registration & submission fields – {{ contest_entry.submission.field_name }}

Adding Validations

Now that we have fields to collect, we should add validations to make sure the user is submitting valid data.

1. Update your entry form partial to now read:

   {% partial name: "form" %}
     <script>
       var rules = {
         'registration[email]': {required: true},
         'submission[celeb]': {required: true},
         'submission[before_photo]': {required: true},
         'submission[after_photo]': {required: true}
       };
     </script>
   
     {% contest_form rules_var: "rules" %}
       <h4>Celeb Photo Contest Entry Form</h4>
   
       {% unless contest_user_is_registered %}
         <div>
   	Name: <input type="text" name="registration[name]"><br>
           Email: <input type="text" name="registration[email]"><br>
         </div>
       {% endunless %}
   
       <hr>
   
       Celeb: <input type="text" name="submission[celeb]"><br>
       Before Photo: {% image_upload_field name:'submission[before_photo]' %}<br>
       After Photo: {% image_upload_field name:'submission[after_photo]' %}<br>
   
       <div>
         <input type="submit" value="Submit">
       </div>
     {% endcontest_form %}
   {% endpartial %}
   

1. Click "Save Settings" then "Return to Facebook Page". You should now be prompted with an error if you try submitting without any data.

If this validation approach seems familiar, it should. Validation with contest forms works exactly the same as it does with signup forms. For more details on validations in contests, see IDN:Contest Validation Rules.

Gallery

Now comes the fun part. Let's display accepted entries in a gallery view.

1. Go back to the Settings Page
2. Update your application's code to now read:

{% partial name: "form" %}
  <script>
    var rules = {
      'registration[email]': {required: true},
      'submission[celeb]': {required: true},
      'submission[before_photo]': {required: true},
      'submission[after_photo]': {required: true}
    };
  </script>

  {% contest_form rules_var: "rules" %}
    <h4>Celeb Photo Contest Entry Form</h4>

    {% unless contest_user_is_registered %}
      <div>
	Name: <input type="text" name="registration[name]"><br>
        Email: <input type="text" name="registration[email]"><br>
      </div>
    {% endunless %}

    <hr>

    Celeb: <input type="text" name="submission[celeb]"><br>
    Before Photo: {% image_upload_field name:'submission[before_photo]' %}<br>
    After Photo: {% image_upload_field name:'submission[after_photo]' %}<br>

    <div>
      <input type="submit" value="Submit">
    </div>
  {% endcontest_form %}
{% endpartial %}

{% partial name: "confirmation" %}
  <h4>Success!</h4>
  <p>Thank you, <strong>{{ contest_entry.registration.name }}</strong> for submitting your entry.</p>

  <div>
    Email: {{ contest_entry.registration.email }}<br>
    Before Photo: <img src="{{ contest_entry.submission.before_photo }}"><br>
    After Photo: <img src="{{ contest_entry.submission.after_photo }}">
  </div>
{% endpartial %}

<h3>Blush Magazine Celeb Photo Contest</h3>
<p>Show us your favorite before and after photos of celebs!</p>

<hr>

{% contest %}
    <p>
        {% contest_form_link entry_form_partial: "form" success_partial: "confirmation" %}
            Click here to enter
        {% endcontest_form_link %}
    </p>

  {% for entry in contest.contest_entries %}
    <div>
      <strong>{{ entry.submission.celeb }}</strong><br>
      Submitted by {{ entry.contest_user.name }}
      <div>
        {{ entry.submission.before_photo | resize_to: "200" | img_tag }}
        {{ entry.submission.after_photo | resize_to: "200" | img_tag }}
      </div>
    </div>
  {% endfor %}
{% endcontest %}

1. Click "Save Changes" then "Return to Facebook Page". You should see your approved entries under the submission link

We'll expand on the Gallery in Chapter 6, for now our Gallery shows the latest submissions.

Moderation

Moderating the your contest entries is accomplished via Involver's Audience Management Platform (AMP).

• Contests are grouped by Outlet in AMP; if you haven't already added your Fan Page as an Outlet, then please do so first on the Social Apps tab.
• By default contest entries start in a pending state to prevent any unwanted content to be published to your page automatically
• If you want to retroactively moderate your contest entries, simply check the "Automatically Approve Contest Entries" setting available on the contest feature block settings page

Contest entries can be one of the following states:

• Pending (grey border) - This is the default state, unless you have the auto approve setting enabled.
• Approved (green border) - When this state is set, then the contest entry will be available in the context variable contest.contest_entries when displaying the entries on the front-end.
• Unapproved (red border) - Will mark an entry to be not available in any context variable to display.
• Winner (green border) - This is a way to classify an entry in a special context variable contest.winning_contest_entries for display on the front-end

To change the state of the entry, simply click the corresponding icon to toggle the state.

If you would like to update the state for a number of entries then select the entries using the check box and then choose and update action from the "Actions.." select box in the upper right corner.

Next Steps

You've now built an application that collects user generated content. We've looked at customizing the submission form and success page, moderating submitted content and wiring up a simple gallery to show approved entries.

Take a look at the links below to read more about the different components of the contest feature block. Add new fields and validations to your form. Experiment with different success messages and gallery structure.

contest
contest_form_link
contest_user

On to Chapter 6

detail_view.jpg (image/jpeg)
Involver Content Manager.jpg (image/jpeg)
moderation_states.jpg (image/jpeg)
20110406-j94wramj3my3w8m2baex4ypd6p.jpg (image/jpeg)
20110406-rrh5w8761gmx2j4yf96i55dx8w.jpg (image/jpeg)
20110406-mx9q6ebwhx24wxcg3yn2i4c7ik.jpg (image/jpeg)